\name{score}
\alias{score}
\title{Score a Scale}
\description{This function is designed to facilitate scoring scales/questionaires.
}
\usage{
score(dat, reverse = NULL, limits = NULL, mean = TRUE,
  reliability = FALSE, na.rm = TRUE, ...)
}
\arguments{
\item{dat}{
  Variable(s) to be scored.  Multiple variables must be objects of class \code{matrix} or \code{data.frame} or conformable to a data frame via \code{as.data.frame}.  A single variable may be passed as a vector; the only option would be to reverse code it.
}
\item{reverse}{
  A vector specifying the columns to be reversed prior to scoring and calculating reliability.  May either give the column's positions or their names.  Defaults to \code{NULL}.
}
\item{limits}{
  This should be a numeric/integer vector of length 2 giving the \emph{possible} limits of the scale.  This is important in order to properly reverse score variables.  Note that currently it is assumed that there is only one set of limits for the entire scale.  That is, if variable A can range from 1-5, then so can variable B, etc.
}
  \item{mean}{
Logical value.  Controls whether the mean or the sum of the variables is calculated.  Defaults to \code{mean = TRUE}.
}
  \item{reliability}{
Logical value.  If \code{reliability = TRUE}, then \code{\link[psych]{omega}} from package \pkg{psych} is used to calculate various estimates of reliability including Guttman's \eqn{\lambda_{6}}{lambda6}, \eqn{\omega_{h}}{hierarchical omega}, and Cronbach's \eqn{\alpha}{alpha} on the variables.
}
  \item{na.rm}{
Logical whether or not to remove missing (\code{NA}) values prior to scoring.  Defaults to \code{na.rm = TRUE}.  Note, \code{na.rm} is set to \code{FALSE} if \code{mean = FALSE} (i.e., asking for summed scores) because summing is non-sensical over missing values.
}
  \item{\dots}{\code{\dots} additional arguments to be passed to \code{omega}.
}
}
\details{
  Currently, it is only able to handle basic algorithms like summing or finding the mean.  Also, if there are subscales, those must be scored one at a time.  Future version may accomodate more complex algorithms and also provide a straightforward mechanism to ask for scores on subscales.

  Also, the formula for reverse scoring can only handle positive limits.  That is the lower possible limit must be >= 0.
}
\value{
  \item{score}{A vector giving the scores.}
  \item{reliability}{\code{NULL} if \code{reliability = FALSE}, otherwise, an object of class \code{psych} and \code{omega} containing reliability information (from \code{\link[psych]{omega}}) for the scale.}
}
%% \references{}
\author{Joshua Wiley, \url{http://joshuawiley.com/}}

\seealso{\code{\link[psych]{omega}}, \code{\link{rowMeans}}, \code{\link{rowSums}}}

\examples{
## A simple example with and without reverse scoring
score(dat = c(1, 2, 2, 2, 4), limits = c(1, 5))
score(dat = c(1, 2, 2, 2, 4), reverse = 1, limits = c(1, 5))

## A bit of a silly example finding the "reliability" of the \code{mtcars} dataset
score(dat = mtcars, reliability = TRUE)
}
\keyword{misc}
